home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2007 September / PCWSEP07.iso / Software / Linux / Linux Mint 3.0 Light / LinuxMint-3.0-Light.iso / casper / filesystem.squashfs / usr / include / libpurple / accountopt.h < prev    next >
Encoding:
C/C++ Source or Header  |  2007-05-04  |  9.8 KB  |  363 lines
  1. /**
  2.  * @file accountopt.h Account Options API
  3.  * @ingroup core
  4.  *
  5.  * purple
  6.  *
  7.  * Purple is the legal property of its developers, whose names are too numerous
  8.  * to list here.  Please refer to the COPYRIGHT file distributed with this
  9.  * source distribution.
  10.  *
  11.  * This program is free software; you can redistribute it and/or modify
  12.  * it under the terms of the GNU General Public License as published by
  13.  * the Free Software Foundation; either version 2 of the License, or
  14.  * (at your option) any later version.
  15.  *
  16.  * This program is distributed in the hope that it will be useful,
  17.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19.  * GNU General Public License for more details.
  20.  *
  21.  * You should have received a copy of the GNU General Public License
  22.  * along with this program; if not, write to the Free Software
  23.  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  24.  */
  25. #ifndef _PURPLE_ACCOUNTOPT_H_
  26. #define _PURPLE_ACCOUNTOPT_H_
  27.  
  28. #include "prefs.h"
  29.  
  30. /**
  31.  * An option for an account.
  32.  *
  33.  * This is set by protocol plugins, and appears in the account settings
  34.  * dialogs.
  35.  */
  36. typedef struct
  37. {
  38.     PurplePrefType type;      /**< The type of value.                     */
  39.  
  40.     char *text;             /**< The text that will appear to the user. */
  41.     char *pref_name;        /**< The name of the associated preference. */
  42.  
  43.     union
  44.     {
  45.         gboolean boolean;   /**< The default boolean value.             */
  46.         int integer;        /**< The default integer value.             */
  47.         char *string;       /**< The default string value.              */
  48.         GList *list;        /**< The default list value.                */
  49.  
  50.     } default_value;
  51.  
  52.     gboolean masked;
  53.  
  54. } PurpleAccountOption;
  55.  
  56. /**
  57.  * A username split.
  58.  *
  59.  * This is used by some protocols to separate the fields of the username
  60.  * into more human-readable components.
  61.  */
  62. typedef struct
  63. {
  64.     char *text;             /**< The text that will appear to the user. */
  65.     char *default_value;    /**< The default value.                     */
  66.     char  field_sep;        /**< The field separator.                   */
  67.  
  68. } PurpleAccountUserSplit;
  69.  
  70. #ifdef __cplusplus
  71. extern "C" {
  72. #endif
  73.  
  74. /**************************************************************************/
  75. /** @name Account Option API                                              */
  76. /**************************************************************************/
  77. /*@{*/
  78.  
  79. /**
  80.  * Creates a new account option.
  81.  *
  82.  * @param type      The type of option.
  83.  * @param text      The text of the option.
  84.  * @param pref_name The account preference name for the option.
  85.  *
  86.  * @return The account option.
  87.  */
  88. PurpleAccountOption *purple_account_option_new(PurplePrefType type, const char *text,
  89.                                            const char *pref_name);
  90.  
  91. /**
  92.  * Creates a new boolean account option.
  93.  *
  94.  * @param text          The text of the option.
  95.  * @param pref_name     The account preference name for the option.
  96.  * @param default_value The default value.
  97.  *
  98.  * @return The account option.
  99.  */
  100. PurpleAccountOption *purple_account_option_bool_new(const char *text,
  101.                                                 const char *pref_name,
  102.                                                 gboolean default_value);
  103.  
  104. /**
  105.  * Creates a new integer account option.
  106.  *
  107.  * @param text          The text of the option.
  108.  * @param pref_name     The account preference name for the option.
  109.  * @param default_value The default value.
  110.  *
  111.  * @return The account option.
  112.  */
  113. PurpleAccountOption *purple_account_option_int_new(const char *text,
  114.                                                const char *pref_name,
  115.                                                int default_value);
  116.  
  117. /**
  118.  * Creates a new string account option.
  119.  *
  120.  * @param text          The text of the option.
  121.  * @param pref_name     The account preference name for the option.
  122.  * @param default_value The default value.
  123.  *
  124.  * @return The account option.
  125.  */
  126. PurpleAccountOption *purple_account_option_string_new(const char *text,
  127.                                                   const char *pref_name,
  128.                                                   const char *default_value);
  129.  
  130. /**
  131.  * Creates a new list account option.
  132.  *
  133.  * The list passed will be owned by the account option, and the
  134.  * strings inside will be freed automatically.
  135.  *
  136.  * The list is a list of PurpleKeyValuePair items. The key is the ID stored and
  137.  * used internally, and the value is the label displayed.
  138.  *
  139.  * @param text      The text of the option.
  140.  * @param pref_name The account preference name for the option.
  141.  * @param list      The key, value list.
  142.  *
  143.  * @return The account option.
  144.  */
  145. PurpleAccountOption *purple_account_option_list_new(const char *text,
  146.                                                 const char *pref_name,
  147.                                                 GList *list);
  148.  
  149. /**
  150.  * Destroys an account option.
  151.  *
  152.  * @param option The option to destroy.
  153.  */
  154. void purple_account_option_destroy(PurpleAccountOption *option);
  155.  
  156. /**
  157.  * Sets the default boolean value for an account option.
  158.  *
  159.  * @param option The account option.
  160.  * @param value  The default boolean value.
  161.  */
  162. void purple_account_option_set_default_bool(PurpleAccountOption *option,
  163.                                           gboolean value);
  164.  
  165. /**
  166.  * Sets the default integer value for an account option.
  167.  *
  168.  * @param option The account option.
  169.  * @param value  The default integer value.
  170.  */
  171. void purple_account_option_set_default_int(PurpleAccountOption *option,
  172.                                          int value);
  173.  
  174. /**
  175.  * Sets the default string value for an account option.
  176.  *
  177.  * @param option The account option.
  178.  * @param value  The default string value.
  179.  */
  180. void purple_account_option_set_default_string(PurpleAccountOption *option,
  181.                                             const char *value);
  182.  
  183. /**
  184.  * Sets the masking for an account option.
  185.  *
  186.  * @param option The account option.
  187.  * @param masked  The masking.
  188.  */
  189. void
  190. purple_account_option_set_masked(PurpleAccountOption *option, gboolean masked);
  191.  
  192. /**
  193.  * Sets the list values for an account option.
  194.  *
  195.  * The list passed will be owned by the account option, and the
  196.  * strings inside will be freed automatically.
  197.  *
  198.  * The list is in key, value pairs. The key is the ID stored and used
  199.  * internally, and the value is the label displayed.
  200.  *
  201.  * @param option The account option.
  202.  * @param values The default list value.
  203.  */
  204. void purple_account_option_set_list(PurpleAccountOption *option, GList *values);
  205.  
  206. /**
  207.  * Adds an item to a list account option.
  208.  *
  209.  * @param option The account option.
  210.  * @param key    The key.
  211.  * @param value  The value.
  212.  */
  213. void purple_account_option_add_list_item(PurpleAccountOption *option,
  214.                                        const char *key, const char *value);
  215.  
  216. /**
  217.  * Returns the specified account option's type.
  218.  *
  219.  * @param option The account option.
  220.  *
  221.  * @return The account option's type.
  222.  */
  223. PurplePrefType purple_account_option_get_type(const PurpleAccountOption *option);
  224.  
  225. /**
  226.  * Returns the text for an account option.
  227.  *
  228.  * @param option The account option.
  229.  *
  230.  * @return The account option's text.
  231.  */
  232. const char *purple_account_option_get_text(const PurpleAccountOption *option);
  233.  
  234. /**
  235.  * Returns the account setting for an account option.
  236.  *
  237.  * @param option The account option.
  238.  *
  239.  * @return The account setting.
  240.  */
  241. const char *purple_account_option_get_setting(const PurpleAccountOption *option);
  242.  
  243. /**
  244.  * Returns the default boolean value for an account option.
  245.  *
  246.  * @param option The account option.
  247.  *
  248.  * @return The default boolean value.
  249.  */
  250. gboolean purple_account_option_get_default_bool(const PurpleAccountOption *option);
  251.  
  252. /**
  253.  * Returns the default integer value for an account option.
  254.  *
  255.  * @param option The account option.
  256.  *
  257.  * @return The default integer value.
  258.  */
  259. int purple_account_option_get_default_int(const PurpleAccountOption *option);
  260.  
  261. /**
  262.  * Returns the default string value for an account option.
  263.  *
  264.  * @param option The account option.
  265.  *
  266.  * @return The default string value.
  267.  */
  268. const char *purple_account_option_get_default_string(
  269.     const PurpleAccountOption *option);
  270.  
  271. /**
  272.  * Returns the default string value for a list account option.
  273.  *
  274.  * @param option The account option.
  275.  *
  276.  * @return The default list string value.
  277.  */
  278. const char *purple_account_option_get_default_list_value(
  279.     const PurpleAccountOption *option);
  280.  
  281. /**
  282.  * Returns the masking for an account option.
  283.  *
  284.  * @param option The account option.
  285.  *
  286.  * @return The masking.
  287.  */
  288. gboolean
  289. purple_account_option_get_masked(const PurpleAccountOption *option);
  290.  
  291. /**
  292.  * Returns the list values for an account option.
  293.  *
  294.  * @param option The account option.
  295.  *
  296.  * @return The list values.
  297.  */
  298. const GList *purple_account_option_get_list(const PurpleAccountOption *option);
  299.  
  300. /*@}*/
  301.  
  302.  
  303. /**************************************************************************/
  304. /** @name Account User Split API                                          */
  305. /**************************************************************************/
  306. /*@{*/
  307.  
  308. /**
  309.  * Creates a new account username split.
  310.  *
  311.  * @param text          The text of the option.
  312.  * @param default_value The default value.
  313.  * @param sep           The field separator.
  314.  *
  315.  * @return The new user split.
  316.  */
  317. PurpleAccountUserSplit *purple_account_user_split_new(const char *text,
  318.                                                   const char *default_value,
  319.                                                   char sep);
  320.  
  321. /**
  322.  * Destroys an account username split.
  323.  *
  324.  * @param split The split to destroy.
  325.  */
  326. void purple_account_user_split_destroy(PurpleAccountUserSplit *split);
  327.  
  328. /**
  329.  * Returns the text for an account username split.
  330.  *
  331.  * @param split The account username split.
  332.  *
  333.  * @return The account username split's text.
  334.  */
  335. const char *purple_account_user_split_get_text(const PurpleAccountUserSplit *split);
  336.  
  337. /**
  338.  * Returns the default string value for an account split.
  339.  *
  340.  * @param split The account username split.
  341.  *
  342.  * @return The default string.
  343.  */
  344. const char *purple_account_user_split_get_default_value(
  345.         const PurpleAccountUserSplit *split);
  346.  
  347. /**
  348.  * Returns the field separator for an account split.
  349.  *
  350.  * @param split The account username split.
  351.  *
  352.  * @return The field separator.
  353.  */
  354. char purple_account_user_split_get_separator(const PurpleAccountUserSplit *split);
  355.  
  356. /*@}*/
  357.  
  358. #ifdef __cplusplus
  359. }
  360. #endif
  361.  
  362. #endif /* _PURPLE_ACCOUNTOPT_H_ */
  363.